Plugin SDK
 
If you have any questions or problems developing plugins for Samurize, be sure to stop by the samurize.com forums for help from other community members and the development team.

NOTES:
The SAMURIZE_PLUGIN_CHAR and SAMURIZE_PLUGIN_INT types are defined as

#define SAMURIZE_PLUGIN_CHAR extern "C" __declspec(dllexport) char* __stdcall
#define SAMURIZE_PLUGIN_INT extern "C" __declspec(dllexport) int __stdcall

In Delphi they are simply the PChar and Integer types.

Function List
 
BOOL APIENTRY DllMain(HANDLE hModule, DWORD ul_reason_for_call, LPVOID lpReserved)
 
The standard DLLMain function. You can use this function to do one-off initialization and de-initialization for your plugin using the DLL_PROCESS_ATTACH and DLL_PROCESS_DETACH reasons for call.

See here for more information.

Parameters:
  • hModule - Handle to the DLL module
  • ul_reason_for_call - Indicates why the DLL entry-point function is being called. This parameter can be one of the following values.
    • DLL_PROCESS_ATTACH - The DLL is being loaded by Samurize (ie. when the first meter that uses the plugin is created)
    • DLL_PROCESS_DETACH - The DLL is being unloaded by Samurize (ie. after the last meter that uses the plugin has been destroyed)
    • DLL_THREAD_ATTACH - not used by Samurize
    • DLL_THREAD_DETACH - not used by Samurize
  • lpReserved - If fdwReason is DLL_PROCESS_ATTACH, lpvReserved is NULL for dynamic loads and non-NULL for static loads. If fdwReason is DLL_PROCESS_DETACH, lpvReserved is NULL if DllMain has been called by using FreeLibrary and non-NULL if DllMain has been called during process termination.
Return Value:
This function should return TRUE.
 
SAMURIZE_PLUGIN_CHAR init()
 
The init() function tells Samurize the names of the functions your source plugin provides. It should return a list like so: "Func1|Func2|...|FuncN"

Return Value:
A list of all the functions your source plugin provides eg. "My Function 1|Some other function|And another"
 
 
SAMURIZE_PLUGIN_INT dlltype()
 
Tells Samurize what type of plugin this is. If this function is declared, Samurize will assume you are using the SDK v2.0;
  • All source functions your plugin provides will be called with an additional first parameter, the meter's unique_id.
  • dllstartup will be called for each meter created that uses your plugin (if you provide that function)
  • dllshutdown when a meter that uses your plugin is deleted (if you provide that function)
Return Value:
The value you should return is a summation of any or all of the following values:
1: Source plugin
2: Visual plugin
4: Input plugin
... (more to follow!)

eg. returning 2 tells Samurize your plugin is a visual plugin. Returning 3 tells Samurize your plugin is a visual plugins AND has a source plugin component as well.
 
SAMURIZE_PLUGIN_CHAR getinfo(int infonum)
 
This function should return information about your plugin depending on the passed integer value. This information is displayed when the 'About' button is pressed in the config editor when your plugin is selected.

This function is optional.

Parameters:
  • infonum - an integer value indicating the information that should be returned:
    1. Plugin name
    2. Author name
    3. Plugin version
    4. Creation date
    5. Last modified date
    6. Website
    7. Contact email address
    8. Description of plugin
 
SAMURIZE_PLUGIN_INT dllstartup(HWND hwnd, int dlltype)
 
dllstartup() is called every time Samurize creates a meter that uses this plugin.
Any memory allocation needed on a meter-by-meter basis should be done in this function.

Parameters:
  • hwnd - the window handle of the instance of Samurize that called this function.
  • dlltype - indicates the meter 'type' (1 for source plugins, 2 for visual plugins) that is being initialized.
Return Value:
This function should return a unique integer ID that Samurize remembers and uses for other functions (this is so multiple instances of Samurize that use this plugin do not conflict).
If your plugin is very simple and does not need to keep any global variables that may cause conflicts, just return 0 (or omit this function).
 
SAMURIZE_PLUGIN_INT dllshutdown(int id)
 
dllshutdown() is called every time a meter using the plugin is destroyed by Samurize.
Any memory releasing needed on a meter-by-meter basis should be done in this function.
If your plugin does not need to free any memory, this function may be omitted.

Parameters:
  • id - the unique ID your plugin assigned to the meter (returned by dllstartup)
Return Value:
This function should always return 0.
 
SAMURIZE_PLUGIN_CHAR save_xml(int id)
 
save_xml() is called when the config is being saved to an XML file by the Samurize server executable. Your plugin should return its settings in XML format as follows:

	<SETTING ATTR="attribute1">attribute value</SETTING>
	<SETTING ATTR="myattribute">123</SETTING>
	<SETTING ATTR="anotherattribute">some value</SETTING>
Parameters:
  • id - the unique ID assigned to the meter by the dllstartup() function
SAMURIZE_PLUGIN_INT pastemeter(int source_id, int dest_id)
 
pastemeter is called when a meter is pasted in the config editor. Your plugin should clone the settings from the source meter (indicated by source_id) to the cloned meter (indicated by dest_id).

Parameters:
  • source_id - the unique ID assigned to the source meter by the dllstartup() function
  • dest_id - the unique ID assigned to the destination meter by the dllstartup() function
Return Value:
This function should return 0.